home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1998 #4 / Amiga Plus CD - 1998 - No. 4.iso / pd / disk / fback-dist / doc / fback14c.doc next >
Text File  |  1998-02-22  |  23KB  |  540 lines
  1.  
  2.   *********************************************************************
  3.                               FBack  V1.4c
  4.                             By Chris De Maeyer
  5.                             For  AmigaDOS  68k
  6.   *********************************************************************
  7.  
  8.  
  9.   0. Contents
  10.     ----------
  11.  
  12.      1. Introduction
  13.         1.1. Legal
  14.         1.2. What it does...
  15.         1.3. Requirements
  16.         1.4. Contact address
  17.         1.5. Development info
  18.         1.6. Versions
  19.  
  20.      2. Using it
  21.         2.1. Command line options
  22.         2.2. Examples
  23.  
  24.      3. Appendix
  25.         3.1. Common problems
  26.         3.2. Error messages
  27.         3.3. The future
  28.         3.4. About me
  29.  
  30.  
  31.   1. Introduction
  32.     --------------
  33.  
  34.      If you have used this program before try to make the effort to read this doc
  35.      again. Some useful info is updated, not listed in previous versions.
  36.  
  37.      Read also 'fmirr14c.doc' for changes !
  38.           
  39.      1.1. Legal
  40.          -------
  41.           Type  : - (E)MAILWARE
  42.  
  43.           Terms : - no modifications to any file in this archive
  44.                   - add no additional files to this archive
  45.                   - use this program longer than 30 days, then you should
  46.                     reward the author with a postcard/letter/email, hence the term
  47.                     mailware
  48.                   - author can not be held responsible for data loss, the program
  49.                     has been tested and the behaviour has been described below
  50.                   - any commercial distribution is prohibited (except on Aminet).
  51.  
  52.  
  53.      1.2. What it does
  54.          --------------
  55.           'FBack' is a file copy tool. It will check the archive bit of files
  56.           and copy them if the archive bit is not set. After copying it will
  57.           add the archive bit. It can be used to perform a 'Daily' backup of
  58.           changed files.
  59.           
  60.           As an option you can run the program in GUI mode, this will open up
  61.           a window which keeps up with the process. For now, when processing is
  62.           finished the window will remain open until you close it with the close
  63.           gadget. Unless you specify NOWAIT, then the window is closed immediately
  64.           after processing. In this mode the 'Current' gadget displays the files it
  65.           is scanning. In CLI mode it merely reports the directories it is scanning
  66.           (let me know if you want files here too [as an option]).
  67.           
  68.           On request of some users a CLONE option has been added, meaning the
  69.           date/time is preserved on the backup.
  70.           
  71.           The filenotes are copied by default, specifying the NOCOMMENT option
  72.           will suppress this.
  73.           
  74.           The program includes a batch mode, paths and options are then specified
  75.           with a configuration file. Several entries are allowed.
  76.           
  77.           Further, the filenotes are copied or not copied with NOCOMMENT option.
  78.           
  79.           Some extra statistics, the estimated processor time (for now only in
  80.           second(s)) are displayed.
  81.           
  82.           'FMirror' is included. Its purpose is to delete files which no longer
  83.           exist in the original directory, thus creating a mirror.
  84.           
  85.           There has been a remark concerning the mirror concept in combination
  86.           with the pack mode, if you take it word for word, issuing PACK is no
  87.           EXACT mirror (jeezes!). Mirroring is portrayed in this implementation as
  88.           following concept: you have a copy (normal or packed) on the backup volume
  89.           of what is on your source path (Comprendo!).
  90.  
  91.  
  92.      1.3. Requirements
  93.          --------------
  94.           Properly installed Amiga ROM 2.04+.
  95.           Needs XPK library when using this option.
  96.           GUI window uses standard GADTOOLS library.
  97.           Needs Argue (V1.3a) to use FBackGUI, FMirrorGUI.
  98.  
  99.  
  100.      1.4. Contact address
  101.          -----------------
  102.           For mail/information/problems/gifts/bugs etc. write to the address
  103.           below, state version & add postage for reply:
  104.  
  105.                  Visionary Software
  106.                  tav. Chris De Maeyer
  107.  
  108.                  Norbertijnenstraat 4
  109.                  B-2040       BELGIUM
  110.                  EUROPE
  111.  
  112.                  Internet :cdemaeyer1@mmm.com
  113.                  Alternate:ceppe@geocities.com
  114.                  Homepage :http://www.geocities.com/SiliconValley/Peaks/8452   
  115.  
  116.  
  117.      1.5. Development info
  118.          ------------------
  119.           Sources were written in C and compiled using SAS/C V6.58.
  120.  
  121.           All file I/O has been coded using standard system library
  122.           functions (V38+).
  123.  
  124.  
  125.      1.6. Versions
  126.          ----------
  127.         
  128.           The actual version can be determined by typing 'version fback' in a
  129.           CLI window.
  130.           It is recommended to always upgrade to the latest version.
  131.  
  132.           V0.9  TEST RELEASE 
  133.                 - first internal test version.
  134.  
  135.           V1.0  FIRST PUBLIC RELEASE 
  136.                 - cleaned up code
  137.                 - adapt stack size + compile with stackextend, optimize
  138.                 - first public release.
  139.                  
  140.           V1.1  MAJOR UPDATE 
  141.                 - added file report after processing
  142.                 - shortened output strings + reformat
  143.                 - changed ExamineDir() flow, performs better with patterns
  144.                 - message to indicate NOCOPY mode
  145.                 - fixed error in document (FROM/A & TO/A examples).
  146.  
  147.           V1.1a MINOR UPDATE 
  148.                 - changed some buffer sizes for speed, copybuffer = 16Kb.
  149.           
  150.           V1.2  MAJOR UPDATE
  151.                 - added packing mode
  152.                 - added XPK packer/unpacker
  153.                 - added date in version string.
  154.           
  155.           V1.2a MINOR UPDATE
  156.                 - updated some internal values
  157.                 - added Argue GUI
  158.                 - added BUF option.        
  159.                 
  160.           V1.2b MINOR UPDATE
  161.                 - added FORCE option
  162.                 - changed some displayed strings.
  163.                 
  164.           V1.2c MINOR UPDATE
  165.                 - replaced SAS pattern match function with 'dos.library'
  166.                   function MatchPatternNoCase()
  167.                 - fixed pattern matching.
  168.                                       
  169.           V1.3  MAJOR UPDATE
  170.                 - archive bits are also set on destination (Oops!)
  171.                 - added GUI window option 
  172.                 - added NOWAIT option
  173.                 - added CLONE option, to keep date on destination.
  174.  
  175.           V1.3a MINOR UPDATE
  176.                 - filenotes of files are copied now
  177.                 - added NOCOMMENT option
  178.                 - code generation with SAS/C 6.58.
  179.                 
  180.           V1.4  MAJOR UPDATE
  181.                 - fixed traversing the directory tree
  182.                 - HandleIDCMP() uses Wait() now
  183.                 - added estimated processor time (and total time) report
  184.                 - changed output attributes of some strings
  185.                 - FROM, TO paths are checked now
  186.                 - filenotes of directories are copied now
  187.                 - added configuration file mode (batch).
  188.                 
  189.           V1.4a MINOR UPDATE
  190.                 - added BEFORE/ASOF date possibility
  191.                 
  192.                 Remark: I tested with async I/O functions but these
  193.                         gave a poor result ! Why ? Rather simple to be honest,
  194.                         I can not do/find any other task to do while copy is
  195.                         busy...
  196.                         
  197.                         ASYNC TEST RESULTS
  198.                         ------------------
  199.                         Mb     Buffer      Time To Backup
  200.                         ---------------------------------
  201.                         24     16 Kb        98 seconds
  202.                         24     64 Kb        68 seconds
  203.                         
  204.                         1.5    16 Kb        30 seconds (small files)
  205.                          
  206.                         See table with BUF option for reference to normal
  207.                         implemented routines.
  208.                         
  209.           V1.4b MINOR UPDATE
  210.                 - support for more files               
  211.                 - default copy buffer size 32Kb
  212.                 
  213.           V1.4c MINOR UPDATE
  214.                 - bugfix in file arrays
  215.                 - aborts on CTRL_C in CLI mode      
  216.                                          
  217.   2. Using it
  218.     ----------
  219.      2.1. Command line options
  220.          ----------------------
  221.           The program uses standard AmigaDOS command templates, so
  222.           typing 'FBack ?' will list all the options available.
  223.  
  224.            Detail explanation of options:
  225.  
  226.              FROM/A       - the source path, a AmigaDOS file pattern may be
  227.                             given.
  228.                             
  229.                                 fe.   BOOT:
  230.                                       BOOT:Prefs/
  231.                                       BOOT:S/#?.keyfile
  232.                                       
  233.                             As you can see, a volume needs no '/'. However, a 
  234.                             directory always needs a '/'.
  235.                             If a volume\directory is chosen, only that part will
  236.                             be checked, to include all subdirectories include the
  237.                             'ALL' switch.
  238.                             
  239.                                 fe.   FBack BOOT: TO BACKUP: ALL
  240.                                       FBack WORK:data/ TO BACKUP:Sys/ PACK=HUFF ALL
  241.                                       Fback WORK:data/calc/#?.wk1 TO BACKUP:Wks/ ALL
  242.                                                
  243.              TO/A         - the destination path.
  244.              
  245.                                 fe.  BACKUP:
  246.                                      SQ0:Backup/Workbench/
  247.                                      
  248.                             Same rules as above, a volume needs no '/'. A directory
  249.                             always needs an ending '/'. 
  250.                             As you might expect, the 'ALL' switch will create any
  251.                             missing subdirectories in the destination path.
  252.                                      
  253.              NOCOPY/S     - this does exactly what it says, when a file has
  254.                             been modified it is normally copied to the backup
  255.                             location. Adding this parameter prevents this and the
  256.                             program will merely report the file. Call it a SIMULATE
  257.                             mode.
  258.  
  259.              ALL/S        - include subdirectories.
  260.              
  261.              QUIET/S      - no output messages.
  262.  
  263.              PACK=/K      - enables packer mode, supply preferred packer. In this
  264.                             mode make sure your recovery disk includes the XPK library
  265.                             + some XPK unpacker (fe. xpk [included]) to restore files.
  266.                             
  267.                                 fe. PACK=nuke
  268.                                 
  269.              BUF=/K/N     - choose the buffer size used for copying, default is 32 Kb.
  270.                             Size limited only by your available RAM (but do not try to
  271.                             use TOO big sizes, 32 Kb will do fine for most users).
  272.                             
  273.                             *********** READ THIS HERE !!! ***************
  274.                                The buffer size is specified in bytes.
  275.                             **********************************************   
  276.  
  277.                             This table states a test result (on my system!):
  278.                             
  279.                                 Mb    Buffer          Time To Backup
  280.                                 ------------------------------------
  281.                                 24    16 Kb            84 seconds (big files)
  282.                                 24    64 Kb            47 seconds   "    "
  283.                                 24    128Kb            32 seconds   "    "
  284.  
  285.                                 1.5   16 Kb            29 seconds (small files)
  286.                                 1.5   64 Kb            28 seconds    "     "
  287.                                 1.5   128Kb            28 seconds    "     "
  288.                                 
  289.                             Obviously, the speed increase is optimal while backing
  290.                             up large files and vanishes if little files are processed.
  291.                             
  292.              FORCE/S      - specifying this option will ignore the archive bit, thus
  293.                             copying every file (= full backup).
  294.         
  295.              GUI/S        - opens GUI showing some statistics, no more CLI output.
  296.     
  297.              NOWAIT/S     - when using GUI mode, closes the window immediately after
  298.                             processing finishes, otherwise window remains open until you
  299.                             click the close gadget.
  300.                             
  301.              CLONE/S      - clones file date/time to destination.
  302.  
  303.              NOCOMMENT/S  - specifying this option will instruct FBack NOT to copy
  304.                             the filenotes.
  305.  
  306.              CONFIG=/K    - run in batch mode, this parameter contains the filename
  307.                             of the configuration file to process. 
  308.                             
  309.                             Syntax configuration file (text file):
  310.                             
  311.                             ----------------- cut ----------------------
  312.                                 [FBack]
  313.                                 NumberOfPaths = <N>
  314.                                 
  315.                                 [Paths]
  316.                                 SrcPath1 = <source path 1>
  317.                                 DstPath1 = <destination path 1>
  318.                                 ...
  319.                                 SrcPathN = <source path N>
  320.                                 DstPathN = <destination path N>
  321.                                 
  322.                                 [Options]
  323.                                 BOptions1 = <fback options for entry 1>
  324.                                 MOptions1 = <fmirror options for entry 1>
  325.                                 ...
  326.                                 BOptionsN = <fback options for entry N>
  327.                                 MOptionsN = <fmirror options for entry N>
  328.                             ----------------- cut ----------------------
  329.                                  
  330.                             Example: study "MYBACK.CFG" included in the archive.
  331.                                 
  332.                             To start batch mode use a command line like:
  333.                             
  334.                                 fback "" "" cfg=myback.cfg
  335.                                 
  336.                                             or
  337.                                 
  338.                                 fback "" "" config=whatever
  339.                                     
  340.                                     
  341.                             All options are available in batch mode, except for
  342.                             FROM, TO and BUF.
  343.                             Also, batch mode is NOT included in the Argue GUI.
  344.                                          
  345.                             NOTE: To detect in which mode (CLI or GUI) FBack
  346.                                   will run the first option entry is taken.
  347.                                   
  348.                                   Thus, specifying GUI in the 1st option entry
  349.                                   will trigger GUI mode for all subsequent batch
  350.                                   entries.
  351.                                   Leaving GUI out of the 1st option entry will 
  352.                                   run all subsequent entries in CLI mode.    
  353.  
  354.                                   NOWAIT is also only interpreted in the 1st
  355.                                   option entry.
  356.                                   
  357.                                   When running batch mode with GUI, the current
  358.                                   gadget will display the batch entry it is going
  359.                                   to process for a couple of seconds. After the
  360.                                   batch entry is done the "Estimated processor
  361.                                   time" is displayed. When all batch entries are
  362.                                   finished the "Total processor time" will be
  363.                                   shown.
  364.                                   
  365.             BEFORE=/K     This triggers the date selection. Enter the date in DOS
  366.                            format (dd-mmm-yy) meaning this is also localized.
  367.                            
  368.                            For example: 15-okt-97    for Belgian/Dutch users.
  369.                            
  370.             ASOF=/K       Opposite of the previous, will backup files as of the
  371.                            the date given and after it.
  372.                            So,the date given is included in the selection.
  373.           
  374.                                   
  375.            The return code is either RETURN_OK (0) or RETURN_WARN (5) in all
  376.            other cases.
  377.            For some examples look at next section "2.2. Examples".
  378.  
  379.            While in CLI mode the program can be interrupted by pressing CTRL-C.
  380.            
  381.            Or, if you have Argue V1.3a you can use the GUI (FBackGUI) version.
  382.  
  383.            NOTE: the logical sequence to run FBack/FMirror is run FBack first,
  384.                  then run FMirror (as you see in the first example below).
  385.                  Some users do it the other way round (the logic escapes me!).
  386.                  
  387.      2.2. Examples
  388.          ----------
  389.           This section lists some examples of usage.
  390.  
  391.           - Backup changed prefs files:
  392.  
  393.                ; Startup-sequence
  394.                ...
  395.                FBack sys:prefs/env-archive/ to work:backup/prefs/ ALL FORCE QUIET
  396.                FMirror work:backup/prefs/ to sys:prefs/env-archive/ ALL QUIET
  397.                ...
  398.  
  399.           - Mirror a disk at startup & create logfile:
  400.  
  401.                ; Startup-sequence
  402.                ...
  403.                FBack sys: to mirror:boot/ ALL >T:FBack.log
  404.                FMirror mirror:boot/ to sys: ALL >T:FMirror.log
  405.                ...
  406.                
  407.  
  408.           - Mirror files before shutdown:
  409.           
  410.                .key FLAG
  411.                .bra {
  412.                .ket }
  413.                ; Shutdown script
  414.                echo "Just a moment, valuable files are checked..."
  415.                ;
  416.                if {FLAG} EQ "GFX"
  417.                     FBack work:data/gfx/ to backup:data/gfx/ ALL GUI NOWAIT
  418.                     echo "Gfx data has been saved."
  419.                endif
  420.                if {FLAG} EQ "ALL"
  421.                     FBack work:data/ to mirror:data/ ALL GUI NOWAIT
  422.                     FMirror mirror:data/ work:data/ ALL GUI
  423.                     echo "All data has been mirrored."
  424.                endif
  425.                ;
  426.                FBack sys:prefs/ to mirror:prefs/ ALL PACK=BZLW QUIET
  427.                echo "System preferences have been saved."
  428.                ; 
  429.                if exists C:Halt
  430.                     echo "It now safe to switch me OFF !"
  431.                     Halt 
  432.                endif
  433.  
  434.           - Backup certain files in a range of dates:
  435.           
  436.                fback data:texts/ backup: all clone asof=01-feb-97 before=10-feb-97
  437.                
  438.             Will backup the files from 01 february 1997 till 09 february 1997.
  439.                
  440.   3. Appendix
  441.     ----------
  442.      3.1. Common problems
  443.          -----------------
  444.  
  445.           Q: It doesn't find its source/backup files ?
  446.           
  447.           A: Enter the correct path: see section 2.1 (FROM,TO option).
  448.  
  449.  
  450.  
  451.           Q: Fback picks up not any file ?
  452.           
  453.           A: Did you end the source path with a '/' ? Leaving it out
  454.              will traverse the entire source drive without touching
  455.              any file. Call it a side-effect !           
  456.  
  457.           
  458.           Q: When I backup to a JAZ/ZIP drive it takes a long time !
  459.           
  460.           A: Add a large number of disk buffers, eg. 'AddBuffers JAZ5: 200'.
  461.           
  462.                     
  463.      3.2. Error messages
  464.          ----------------
  465.  
  466.           'Source/Destination not found'
  467.  
  468.              The entered path could not be located. Correct your paths !
  469.  
  470.           'File not found'
  471.  
  472.              The file you typed could not be found.
  473.  
  474.           'Invalid date'
  475.           
  476.              Enter the date in ADOS format, thus dd-mmm-yyy. Example: 01-jan-97.
  477.           
  478.           'No xxxxx date'
  479.           
  480.              Supply a date with the BEFORE/ASOF keywords.
  481.              
  482.              
  483.           AmigaDOS errors are in format :
  484.  
  485.              'FBack: nnn - message'
  486.                                                               
  487.  
  488.      3.3. The future
  489.          ------------
  490.  
  491.           Any suggestions/motivations/gifts from you are welcome !
  492.           
  493.           Thanks to all guys & dolls sending me (E)MAIL.
  494.  
  495.           It is because of YOU this program keeps getting better and better...
  496.  
  497.  
  498.      3.4. About me
  499.          ----------
  500.          
  501.          Well, I'm working as a "Technical Analist" for a multinational company.
  502.          My main responsibilities are "Implementing and supporting the WINDOWS NT
  503.          LAN/WAN environment" (shame on me !). It's only for the money... give me
  504.          a break ?? (If my bosses read this -> I'm only sucking up the great Amiga   
  505.          community !).
  506.          
  507.          At home I have a Amiga 4000T (68060/50/PPC, 80Mb Fast, 1GB HD, Syquest 105,
  508.          a JAZ, VLab digitizer, Cybervision 64, Y/C genlock, 2 VCR's, etc).
  509.          Which I primarily use for desktop video, animations, LightWaving,
  510.          programming [and making backups (I detect a bit of sarcasm here !)].
  511.  
  512.          I started my Amiga carrier on a A500, upgraded to A2000 and later a 68020
  513.          accelerator card (somewhere in the cellar now). 
  514.          Gosh, I've got a PPC 604e (200Mhz) now !
  515.  
  516.          Anyway, hope you can use the program (I do !).
  517.          
  518.          Other programs available from Aminet or author:
  519.          
  520.                 BCompress       -> Huffman compressor
  521.                 BCrypt          -> encrypt data files with key
  522.                 LCount          -> count lines/records in ASCII/bin file
  523.                 CExt            -> change/delete/number extentions of files
  524.                 DispIFF         -> appicon on WB to display IFF images
  525.                 R3Version       -> version of Real 3D data files + IFF chunk scanner
  526.                 BruVol          -> estimates no. volumes in BRU backup
  527.                 MyLists         -> link lib for data structures
  528.                 UCDoor          -> link lib for MAX's BBS doors
  529.                 LevelMan        -> MAX's door for access requests
  530.                 SysValues       -> MAX's door displays system values
  531.                 CtdlBull        -> STDIO door for BBS bulletins
  532.                 IsamMake        -> make db defs for Redwood's engine
  533.                 MidiTrack       -> monitor for MIDI packets
  534.                 SetMouse        -> switch mouse port
  535.                 FCheck          -> check files via prefs file then backup
  536.                 Cedee           -> GUI CDDA sound player
  537.                 ...
  538.                 
  539.          See yo.
  540.